PC World Komputer 2010 April

home *** CD-ROM | disk | FTP | other *** search

/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-9.10-netbook-remix-PL.iso / casper / filesystem.squashfs / usr / lib / perl5 / Cairo.pm next >

Wrap

Perl POD Document | 2009-03-28 | 22.8 KB | 1,563 lines

# # Copyright (c) 2004-2008 by the cairo perl team (see the file README) # # Licensed under the LGPL, see LICENSE file for more information. # # $Id: Cairo.pm 171 2009-03-28 13:23:55Z tsch $ # package Cairo; use strict; use warnings; use DynaLoader; our @ISA = qw/DynaLoader/; our $VERSION = '1.061'; sub dl_load_flags { $^O eq 'darwin' ? 0x00 : 0x01 } Cairo->bootstrap ($VERSION); # --------------------------------------------------------------------------- # package Cairo; 1; __END__ =head1 NAME Cairo - Perl interface to the cairo library =head1 SYNOPSIS use Cairo; my $surface = Cairo::ImageSurface->create ('argb32', 100, 100); my $cr = Cairo::Context->create ($surface); $cr->rectangle (10, 10, 40, 40); $cr->set_source_rgb (0, 0, 0); $cr->fill; $cr->rectangle (50, 50, 40, 40); $cr->set_source_rgb (1, 1, 1); $cr->fill; $cr->show_page; $surface->write_to_png ('output.png'); =head1 ABSTRACT Cairo provides Perl bindings for the vector graphics library cairo. It supports multiple output targets, including PNG, PDF and SVG. Cairo produces identical output on all those targets. =head1 API DOCUMENTATION This is a listing of the API Cairo provides. For more verbose information, refer to the cairo manual at L<http://cairographics.org/manual/>. =head2 Drawing =head3 Cairo::Context -- The cairo drawing context I<Cairo::Context> is the main object used when drawing with Cairo. To draw with Cairo, you create a I<Cairo::Context>, set the target surface, and drawing options for the I<Cairo::Context>, create shapes with methods like C<$cr-E<gt>move_to> and C<$cr-E<gt>line_to>, and then draw shapes with C<$cr-E<gt>stroke> or C<$cr-E<gt>fill>. I<Cairo::Context>'s can be pushed to a stack via C<$cr-E<gt>save>. They may then safely be changed, without loosing the current state. Use C<$cr-E<gt>restore> to restore to the saved state. =over =item $cr = Cairo::Context->create ($surface) =over =item $surface: I<Cairo::Surface> =back =item $cr-E<gt>save =item $cr->restore =item $status = $cr->status =item $surface = $cr->get_target =item $cr->push_group [1.2] =item $cr->push_group_with_content ($content) [1.2] =over =item $content: I<Cairo::Content> =back =item $pattern = $cr->pop_group [1.2] =item $cr->pop_group_to_source [1.2] =item $surface = $cr->get_group_target [1.2] =item $cr->set_source_rgb ($red, $green, $blue) =over =item $red: double =item $green: double =item $blue: double =back =item $cr->set_source_rgba ($red, $green, $blue, $alpha) =over =item $red: double =item $green: double =item $blue: double =item $alpha: double =back =item $cr->set_source ($source) =over =item $source: I<Cairo::Pattern> =back =item $cr->set_source_surface ($surface, $x, $y) =over =item $surface: I<Cairo::Surface> =item $x: double =item $y: double =back =item $source = $cr->get_source =item $cr->set_antialias ($antialias) =over =item $antialias: I<Cairo::Antialias> =back =item $antialias = $cr->get_antialias =item $cr->set_dash ($offset, ...) =over =item $offset: double =item ...: list of doubles =back =item $cr->set_fill_rule ($fill_rule) =over =item $fill_rule: I<Cairo::FillRule> =back =item $fill_rule = $cr->get_fill_rule =item $cr->set_line_cap ($line_cap) =over =item $line_cap: I<Cairo::LineCap> =back =item $line_cap = $cr->get_line_cap =item $cr->set_line_join ($line_join) =over =item $line_join: I<Cairo::LineJoin> =back =item $line_join = $cr->get_line_join =item $cr->set_line_width ($width) =over =item $width: double =back =item $width = $cr->get_line_width =item $cr->set_miter_limit ($limit) =over =item $limit: double =back =item ($offset, @dashes) = $cr->get_dash [1.4] =item $limit = $cr->get_miter_limit =item $cr->set_operator ($op) =over =item $op: I<Cairo::Operator> =back =item $op = $cr->get_operator =item $cr->set_tolerance ($tolerance) =over =item $tolerance: double =back =item $tolerance = $cr->get_tolerance =item $cr->clip =item $cr->clip_preserve =item ($x1, $y1, $x2, $y2) = $cr->clip_extents [1.4] =item @rectangles = $cr->copy_clip_rectangle_list [1.4] =item $cr->reset_clip =item $cr->fill =item $cr->fill_preserve =item ($x1, $y1, $x2, $y2) = $cr->fill_extents =item $bool = $cr->in_fill ($x, $y) =over =item $x: double =item $y: double =back =item $cr->mask ($pattern) =over =item $pattern: I<Cairo::Pattern> =back =item $cr->mask_surface ($surface, $surface_x, $surface_y) =over =item $surface: I<Cairo::Surface> =item $surface_x: double =item $surface_y: double =back =item $cr->paint =item $cr->paint_with_alpha ($alpha) =over =item $alpha: double =back =item $cr->stroke =item $cr->stroke_preserve =item ($x1, $y1, $x2, $y2) = $cr->stroke_extents =item $bool = $cr->in_stroke ($x, $y) =over =item $x: double =item $y: double =back =item $cr->copy_page =item $cr->show_page =back =cut # --------------------------------------------------------------------------- # =head3 Paths -- Creating paths and manipulating path data $path = [ { type => "move-to", points => [[1, 2]] }, { type => "line-to", points => [[3, 4]] }, { type => "curve-to", points => [[5, 6], [7, 8], [9, 10]] }, ... { type => "close-path", points => [] }, ]; I<Cairo::Path> is a data structure for holding a path. This data structure serves as the return value for C<$cr-E<gt>copy_path_data> and C<$cr-E<gt>copy_path_data_flat> as well the input value for C<$cr-E<gt>append_path>. I<Cairo::Path> is represented as an array reference that contains path elements, represented by hash references with two keys: I<type> and I<points>. The value for I<type> can be either of the following: =over =item C<move-to> =item C<line-to> =item C<curve-to> =item C<close-path> =back The value for I<points> is an array reference which contains zero or more points. Points are represented as array references that contain two doubles: I<x> and I<y>. The necessary number of points depends on the I<type> of the path element: =over =item C<move-to>: 1 point =item C<line_to>: 1 point =item C<curve-to>: 3 points =item C<close-path>: 0 points =back The semantics and ordering of the coordinate values are consistent with C<$cr-E<gt>move_to>, C<$cr-E<gt>line_to>, C<$cr-E<gt>curve_to>, and C<$cr-E<gt>close_path>. =over =item $path = $cr->copy_path =item $path = $cr->copy_path_flat =item $cr->append_path ($path) =over =item $path: I<Cairo::Path> =back =item $bool = $cr->has_current_point [1.6] =item ($x, $y) = $cr->get_current_point =item $cr->new_path =item $cr->new_sub_path [1.2] =item $cr->close_path =item ($x1, $y1, $x2, $y2) = $cr->path_extents [1.6] =item $cr->arc ($xc, $yc, $radius, $angle1, $angle2) =over =item $xc: double =item $yc: double =item $radius: double =item $angle1: double =item $angle2: double =back =item $cr->arc_negative ($xc, $yc, $radius, $angle1, $angle2) =over =item $xc: double =item $yc: double =item $radius: double =item $angle1: double =item $angle2: double =back =item $cr->curve_to ($x1, $y1, $x2, $y2, $x3, $y3) =over =item $x1: double =item $y1: double =item $x2: double =item $y2: double =item $x3: double =item $y3: double =back =item $cr->line_to ($x, $y) =over =item $x: double =item $y: double =back =item $cr->move_to ($x, $y) =over =item $x: double =item $y: double =back =item $cr->rectangle ($x, $y, $width, $height) =over =item $x: double =item $y: double =item $width: double =item $height: double =back =item $cr->glyph_path (...) =over =item ...: list of I<Cairo::Glyph>'s =back =item $cr->text_path ($utf8) =over =item $utf8: string in utf8 encoding =back =item $cr->rel_curve_to ($dx1, $dy1, $dx2, $dy2, $dx3, $dy3) =over =item $dx1: double =item $dy1: double =item $dx2: double =item $dy2: double =item $dx3: double =item $dy3: double =back =item $cr->rel_line_to ($dx, $dy) =over =item $dx: double =item $dy: double =back =item $cr->rel_move_to ($dx, $dy) =over =item $dx: double =item $dy: double =back =back =cut # --------------------------------------------------------------------------- # =head3 Patterns -- Gradients and filtered sources =over =item $status = $pattern->status =item $type = $pattern->get_type [1.2] =item $pattern->set_matrix ($matrix) =over =item $matrix: I<Cairo::Matrix> =back =item $matrix = $pattern->get_matrix =item $pattern = Cairo::SolidPattern->create_rgb ($red, $green, $blue) =over =item $red: double =item $green: double =item $blue: double =back =item $pattern = Cairo::SolidPattern->create_rgba ($red, $green, $blue, $alpha) =over =item $red: double =item $green: double =item $blue: double =item $alpha: double =back =item ($r, $g, $b, $a) = $pattern->get_rgba [1.4] =item $pattern = Cairo::SurfacePattern->create ($surface) =over =item $surface: I<Cairo::Surface> =back =item $pattern->set_extend ($extend) =over =item $extend: I<Cairo::Extend> =back =item $extend = $pattern->get_extend =item $pattern->set_filter ($filter) =over =item $filter: I<Cairo::Filter> =back =item $filter = $pattern->get_filter =item $surface = $pattern->get_surface [1.4] =item $pattern = Cairo::LinearGradient->create ($x0, $y0, $x1, $y1) =over =item $x0: double =item $y0: double =item $x1: double =item $y1: double =back =item ($x0, $y0, $x1, $y1) = $pattern->get_points [1.4] =item $pattern = Cairo::RadialGradient->create ($cx0, $cy0, $radius0, $cx1, $cy1, $radius1) =over =item $cx0: double =item $cy0: double =item $radius0: double =item $cx1: double =item $cy1: double =item $radius1: double =back =item ($x0, $y0, $r0, $x1, $y1, $r1) = $pattern->get_circles [1.4] =item $pattern->add_color_stop_rgb ($offset, $red, $green, $blue) =over =item $offset: double =item $red: double =item $green: double =item $blue: double =back =item $pattern->add_color_stop_rgba ($offset, $red, $green, $blue, $alpha) =over =item $offset: double =item $red: double =item $green: double =item $blue: double =item $alpha: double =back =item @stops = $pattern->get_color_stops [1.4] A color stop is represented as an array reference with five elements: offset, red, green, blue, and alpha. =back =cut # --------------------------------------------------------------------------- # =head3 Transformations -- Manipulating the current transformation matrix =over =item $cr->translate ($tx, $ty) =over =item $tx: double =item $ty: double =back =item $cr->scale ($sx, $sy) =over =item $sx: double =item $sy: double =back =item $cr->rotate ($angle) =over =item $angle: double =back =item $cr->transform ($matrix) =over =item $matrix: I<Cairo::Matrix> =back =item $cr->set_matrix ($matrix) =over =item $matrix: I<Cairo::Matrix> =back =item $matrix = $cr->get_matrix =item $cr->identity_matrix =item ($x, $y) = $cr->user_to_device ($x, $y) =over =item $x: double =item $y: double =back =item ($dx, $dy) = $cr->user_to_device_distance ($dx, $dy) =over =item $dx: double =item $dy: double =back =item ($x, $y) = $cr->device_to_user ($x, $y) =over =item $x: double =item $y: double =back =item ($dx, $dy) = $cr->device_to_user_distance ($dx, $dy) =over =item $dx: double =item $dy: double =back =back =cut # --------------------------------------------------------------------------- # =head3 Text -- Rendering text and sets of glyphs Glyphs are represented as anonymous hash references with three keys: I<index>, I<x> and I<y>. Example: my @glyphs = ({ index => 1, x => 2, y => 3 }, { index => 2, x => 3, y => 4 }, { index => 3, x => 4, y => 5 }); =over =item $cr->select_font_face ($family, $slant, $weight) =over =item $family: string =item $slant: I<Cairo::FontSlant> =item $weight: I<Cairo::FontWeight> =back =item $cr->set_font_size ($size) =over =item $size: double =back =item $cr->set_font_matrix ($matrix) =over =item $matrix: I<Cairo::Matrix> =back =item $matrix = $cr->get_font_matrix =item $cr->set_font_options ($options) =over =item $options: I<Cairo::FontOptions> =back =item $options = $cr->get_font_options =item $cr->set_scaled_font ($scaled_font) [1.2] =over =item $scaled_font: I<Cairo::ScaledFont> =back =item $scaled_font = $cr->get_scaled_font [1.4] =item $cr->show_text ($utf8) =over =item $utf8: string =back =item $cr->show_glyphs (...) =over =item ...: list of glyphs =back =item $face = $cr->get_font_face =item $extents = $cr->font_extents =item $cr->set_font_face ($font_face) =over =item $font_face: I<Cairo::FontFace> =back =item $cr->set_scaled_font ($scaled_font) =over =item $scaled_font: I<Cairo::ScaledFont> =back =item $extents = $cr->text_extents ($utf8) =over =item $utf8: string =back =item $extents = $cr->glyph_extents (...) =over =item ...: list of glyphs =back =back =cut # --------------------------------------------------------------------------- # =head2 Fonts =head3 Cairo::FontFace -- Base class for fonts =over =item $status = $font_face->status =item $type = $font_face->get_type [1.2] =back =cut # --------------------------------------------------------------------------- # =head3 Scaled Fonts -- Caching metrics for a particular font size =over =item $scaled_font = Cairo::ScaledFont->create ($font_face, $font_matrix, $ctm, $options) =over =item $font_face: I<Cairo::FontFace> =item $font_matrix: I<Cairo::Matrix> =item $ctm: I<Cairo::Matrix> =item $options: I<Cairo::FontOptions> =back =item $status = $scaled_font->status =item $extents = $scaled_font->extents =item $extents = $scaled_font->text_extents ($utf8) [1.2] =over =item $utf8: string =back =item $extents = $scaled_font->glyph_extents (...) =over =item ...: list of glyphs =back =item $font_face = $scaled_font->get_font_face [1.2] =item $options = $scaled_font->get_font_options [1.2] =item $font_matrix = $scaled_font->get_font_matrix [1.2] =item $ctm = $scaled_font->get_ctm [1.2] =item $type = $scaled_font->get_type [1.2] =back =cut # --------------------------------------------------------------------------- # =head3 Font Options -- How a font should be rendered =over =item $font_options = Cairo::FontOptions->create =item $status = $font_options->status =item $font_options->merge ($other) =over =item $other: I<Cairo::FontOptions> =back =item $hash = $font_options->hash =item $bools = $font_options->equal ($other) =over =item $other: I<Cairo::FontOptions> =back =item $font_options->set_antialias ($antialias) =over =item $antialias: I<Cairo::AntiAlias> =back =item $antialias = $font_options->get_antialias =item $font_options->set_subpixel_order ($subpixel_order) =over =item $subpixel_order: I<Cairo::SubpixelOrder> =back =item $subpixel_order = $font_options->get_subpixel_order =item $font_options->set_hint_style ($hint_style) =over =item $hint_style: I<Cairo::HintStyle> =back =item $hint_style = $font_options->get_hint_style =item $font_options->set_hint_metrics ($hint_metrics) =over =item $hint_metrics: I<Cairo::HintMetrics> =back =item $hint_metrics = $font_options->get_hint_metrics =back =cut # --------------------------------------------------------------------------- # =head3 FreeType Fonts -- Font support for FreeType If your cairo library supports it, the FreeType integration allows you to load font faces from font files. You can query for this capability with C<Cairo::HAS_FT_FONT>. To actually use this, you'll need the L<Font::FreeType> module. =over =item my $face = Cairo::FtFontFace->create ($ft_face, $load_flags=0) =over =item $ft_face: I<Font::FreeType::Face> =item $load_flags: integer =back This method allows you to create a I<Cairo::FontFace> from a I<Font::FreeType::Face>. To obtain the latter, you can for example load it from a file: my $file = '/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf'; my $ft_face = Font::FreeType->new->face ($file); my $face = Cairo::FtFontFace->create ($ft_face); =back =cut # --------------------------------------------------------------------------- # =head2 Surfaces =head3 I<Cairo::Surface> -- Base class for surfaces =over =item $new = $old->create_similar ($content, $width, $height) =over =item $content: I<Cairo::Content> =item $width: integer =item $height: integer =back =item $status = $surface->status =item $surface->finish =item $surface->flush =item $font_options = $surface->get_font_options =item $content = $surface->get_content [1.2] =item $surface->mark_dirty =item $surface->mark_dirty_rectangle ($x, $y, $width, $height) =over =item $x: integer =item $y: integer =item $width: integer =item $height: integer =back =item $surface->set_device_offset ($x_offset, $y_offset) =over =item $x_offset: integer =item $y_offset: integer =back =item ($x_offset, $y_offset) = $surface->get_device_offset [1.2] =item $surface->set_fallback_resolution ($x_pixels_per_inch, $y_pixels_per_inch) [1.2] =over =item $x_pixels_per_inch: double =item $y_pixels_per_inch: double =back =item $type = $surface->get_type [1.2] =item $status = $surface->copy_page [1.6] =over =item $status: I<Cairo::Status> =back =item $status = $surface->show_page [1.6] =over =item $status: I<Cairo::Status> =back =back =cut # --------------------------------------------------------------------------- # =head3 Image Surfaces -- Rendering to memory buffers =over =item $surface = Cairo::ImageSurface->create ($format, $width, $height) =over =item $format: I<Cairo::Format> =item $width: integer =item $height: integer =back =item $surface = Cairo::ImageSurface->create_for_data ($data, $format, $width, $height, $stride) =over =item $data: image data =item $format: I<Cairo::Format> =item $width: integer =item $height: integer =item $stride: integer =back =item $data = $surface->get_data [1.2] =item $format = $surface->get_format [1.2] =item $width = $surface->get_width =item $height = $surface->get_height =item $stride = $surface->get_stride [1.2] =back =cut # --------------------------------------------------------------------------- # =head3 PDF Surfaces -- Rendering PDF documents =over =item $surface = Cairo::PdfSurface->create ($filename, $width_in_points, $height_in_points) [1.2] =over =item $filename: string =item $width_in_points: double =item $height_in_points: double =back =item $surface = Cairo::PdfSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2] =over =item $callback: L<Cairo::WriteFunc> =item $callback_data: scalar =item $width_in_points: double =item $height_in_points: double =back =item $surface->set_size ($width_in_points, $height_in_points) [1.2] =over =item $width_in_points: double =item $height_in_points: double =back =back =cut # --------------------------------------------------------------------------- # =head3 PNG Support -- Reading and writing PNG images =over =item $surface = Cairo::ImageSurface->create_from_png ($filename) =over =item $filename: string =back =item Cairo::ReadFunc: $data = sub { my ($callback_data, $length) = @_; } =over =item $data: binary image data, of length $length =item $callback_data: scalar, user data =item $length: integer, bytes to read =back =item $surface = Cairo::ImageSurface->create_from_png_stream ($callback, $callback_data) =over =item $callback: L<Cairo::ReadFunc> =item $callback_data: scalar =back =item $status = $surface->write_to_png ($filename) =over =item $filename: string =back =item Cairo::WriteFunc: sub { my ($callback_data, $data) = @_; } =over =item $callback_data: scalar, user data =item $data: binary image data, to be written =back =item $status = $surface->write_to_png_stream ($callback, $callback_data) =over =item $callback: L<Cairo::WriteFunc> =item $callback_data: scalar =back =back =cut # --------------------------------------------------------------------------- # =head3 PostScript Surfaces -- Rendering PostScript documents =over =item $surface = Cairo::PsSurface->create ($filename, $width_in_points, $height_in_points) [1.2] =over =item $filename: string =item $width_in_points: double =item $height_in_points: double =back =item $surface = Cairo::PsSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2] =over =item $callback: L<Cairo::WriteFunc> =item $callback_data: scalar =item $width_in_points: double =item $height_in_points: double =back =item $surface->set_size ($width_in_points, $height_in_points) [1.2] =over =item $width_in_points: double =item $height_in_points: double =back =item $surface->dsc_begin_setup [1.2] =item $surface->dsc_begin_page_setup [1.2] =item $surface->dsc_comment ($comment) [1.2] =over =item $comment: string =back =item $surface->restrict_to_level ($level) [1.6] =over =item $level: I<Cairo::PsLevel> =back =item @levels = Cairo::PsSurface::get_levels [1.6] =item $string = Cairo::PsSurface::level_to_string ($level) [1.6] =over =item $level: I<Cairo::PsLevel> =back =item $surface->set_eps ($eps) [1.6] =over =item $eps: boolean =back =item $eps = $surface->get_eps [1.6] =back =cut # --------------------------------------------------------------------------- # =head3 SVG Surfaces -- Rendering SVG documents =over =item $surface = Cairo::SvgSurface->create ($filename, $width_in_points, $height_in_points) [1.2] =over =item $filename: string =item $width_in_points: double =item $height_in_points: double =back =item $surface = Cairo::SvgSurface->create_for_stream ($callback, $callback_data, $width_in_points, $height_in_points) [1.2] =over =item $callback: L<Cairo::WriteFunc> =item $callback_data: scalar =item $width_in_points: double =item $height_in_points: double =back =item $surface->restrict_to_version ($version) [1.2] =over =item $version: I<Cairo::SvgVersion> =back =item @versions = Cairo::SvgSurface::get_versions [1.2] =item $string = Cairo::SvgSurface::version_to_string ($version) [1.2] =over =item $version: I<Cairo::SvgVersion> =back =back =cut # --------------------------------------------------------------------------- # =head2 Utilities =head3 Version Information -- Run-time and compile-time version checks. =over =item $version = Cairo->version =item $string = Cairo->version_string =item $version_code = Cairo->VERSION =item $version_code = Cairo->VERSION_ENCODE ($major, $minor, $micro) =over =item $major: integer =item $minor: integer =item $micro: integer =back =item $stride = Cairo::Format::stride_for_width ($format, $width) [1.6] =over =item $format: I<Cairo::Format> =item $width: integer =back =back =cut # --------------------------------------------------------------------------- # =head1 SEE ALSO =over =item L<http://cairographics.org/documentation> Lists many available resources including tutorials and examples =item L<http://cairographics.org/manual/> Contains the reference manual =back =head1 AUTHORS =over =item Ross McFarland E<lt>rwmcfa1 at neces dot comE<gt> =item Torsten Schoenfeld E<lt>kaffeetisch at gmx dot deE<gt> =back =head1 COPYRIGHT Copyright (C) 2004-2009 by the cairo perl team =cut